데이터베이스 쿼리 계약 관리하기

DB 연결 설정과 XML 쿼리 계약을 연결하고, 파라미터 타입을 확인합니다.

QCN

전달하려는 주요 내용

목록·상세·저장처럼 SQL이 중심인 업무를 XML 계약으로 관리합니다.

  • HandStack에서는 이러한 반복적인 데이터베이스 작업을 어떻게 효율적으로 관리할까요?
  • 데이터베이스 쿼리를 하나의 계약(Contract)처럼 XML 파일로 관리하는 방법을 알아봅니다.
  • 이를 통해 복잡한 서버 코드 없이 빠르고 명확하게 데이터 로직을 구현할 수 있습니다.
QCN

쿼리 계약이란? (1/2)

  • SQL 쿼리 자체를 하나의 독립적인 파일(*.xml)로 분리하여 관리하는 방식입니다.

  • 개발자는 비즈니스 로직에 집중하고, 데이터 접근은 약속된 *.xml 파일을 통해 처리합니다.

QCN

쿼리 계약이란? (2/2)

  • 장점
    • 코드와 SQL의 분리로 명확한 역할 분담
    • SQL 변경 시 서버 재컴파일을 줄일 수 있음. 계약 반영·캐시 갱신은 별도 확인
    • 쉬운 유지보수 및 재사용성 증가
    • MyBatis 처럼 개발자가 직접 SQL 쿼리를 작성하고 관리
    • 복잡하거나 최적화가 필요한 쿼리, 혹은 데이터베이스 특정 기능을 활용
QCN

지원 데이터베이스 및 연결 설정

  • HandStack은 다양한 데이터베이스를 지원합니다.

    • SQL Server
    • Oracle
    • MySQL & MariaDB
    • PostgreSQL
    • SQLite

  • 데이터베이스 연결 정보는 다음 파일에서 관리합니다.

    • %HANDSTACK_SRC%/2.Modules/dbclient/module.json
QCN

왜 데이터베이스가 필요한가요?

애플리케이션의 핵심은 데이터입니다.

  • 스키마로 컬럼의 타입과 제약조건을 명시합니다.
  • 트랜잭션으로 연관된 변경의 일관성을 관리합니다.
  • 정규화로 중복을 줄이고 JOIN으로 필요한 데이터를 조합합니다.
QCN

연결 문자열 관리

  • HandStack 프로젝트가 이 데이터베이스와 통신하기 위해서는 연결 정보가 필요합니다.
  • 이 연결 정보를 '연결 문자열 (Connection String)'이라고 부릅니다.
  • 연결 문자열은 데이터베이스의 주소, 계정 정보 등을 담고 있는 특별한 텍스트입니다. 이 문자열을 암호화 해서 관리하거나 키를 수급해서 사용해야합니다.
QCN

HandStack 데이터베이스 설정 파일

HandStack은 module.json 파일 하나로 데이터베이스 연결을 관리합니다.

  • 개발 소스 위치

    • $(HANDSTACK_SRC)/2.Modules/dbclient/module.json
    • 프로젝트의 원본 소스에 포함된 설정 파일입니다.

  • 빌드 후 위치

    • $(HANDSTACK_HOME)/modules/dbclient/module.json
    • 실제 실행 환경에서 사용되는 설정 파일입니다.
QCN

module.json 설정 항목 살펴보기 (1/3)

dbclient 모듈의 module.json 파일은 다음과 같은 구조로 되어 있습니다.

QCN

module.json 설정 항목 살펴보기 (2/3)

{
  "ModuleConfig": {
    "DefaultCommandTimeout": 30,
    "DataSource": [
      {
        "ApplicationID": "Default",
        "ProjectID": "Default",
        "DataSourceID": "Main",
        "DataProvider": "SqlServer",
        "ConnectionString": "서버=localhost;데이터베이스=YourDB;...",
        "IsEncryption": "N"
      }
    ]
  }
QCN

module.json 설정 항목 살펴보기 (3/3)

}
QCN

안전한 연결 문자열 관리 (1/2) · 세부 1/2 (1/3)

중요한 접속 정보를 코드에 그대로 노출하는 것은 위험합니다.
HandStack CLI는 간단한 명령어로 연결 문자열을 암호화/복호화하는 기능을 제공합니다.

QCN

안전한 연결 문자열 관리 (1/2) · 세부 1/2 (2/3)

연결 문자열 암호화에 호스트명이 포함되기 때문에 대상 호스트에서 만들어야 합니다.

  • 연결 문자열 암호화
QCN

안전한 연결 문자열 관리 (1/2) · 세부 1/2 (3/3)

handstack encrypt --format=connectionstring --value="[연결 문자열]"
  • 암호화된 문자열 복호화
QCN

안전한 연결 문자열 관리 (1/2) · 세부 2/2

handstack decrypt --format=connectionstring --value="[암호화된 문자열]"
QCN

안전한 연결 문자열 관리 (1/2) · 세부 1/2

암호화된 문자열은 ConnectionString에 넣고 IsEncryption 값을 "Y"로 변경하여 사용합니다.

  • DataSourceID: 여러 DB를 사용할 경우, 이를 구분하는 고유 ID입니다.

  • DataProvider: 연결할 데이터베이스 종류 (예: SqlServer, Oracle, MariaDB 등)

  • ConnectionString: 실제 데이터베이스 연결 정보

  • IsEncryption: 연결 문자열 암호화 여부

QCN

안전한 연결 문자열 관리 (1/2) · 세부 2/2

연결 문자열 복호화에 호스트명을 검증하기 때문에 다른 호스트에서 복호화할 수 없습니다.

QCN

핸즈온: 연결 확인 (1/2)

별도 실습 DB와 전용 계정을 사용합니다. 연결 문자열은 커밋·화면 공유·로그 출력에서 제외합니다.

이제 여러분의 프로젝트에서 데이터베이스 설정 파일을 직접 열어봅시다.

  1. Visual Studio Code에서 $(HANDSTACK_HOME)/modules/dbclient/module.json 파일을 엽니다.
QCN

핸즈온: 연결 확인 (2/2)

  1. ConnectionString 항목을 찾아 로컬 SQL Server 환경에 맞게 수정합니다.

    • 예시: Server=localhost;Database=handstack_db;User Id=sa;Password=your_password;

  2. IsEncryption 값이 "N"인지 확인합니다.


DataSource는 배열([])로 되어 있어, 여러 개의 데이터베이스 접속 정보를 추가할 수 있습니다. 이를 통해 테넌트별로 다른 데이터베이스를 연결하는 것도 가능합니다.

QCN

잠깐, 구분해 보기

계약 파일이 맞아도 다른 DB에서 실행될 수 있을까요?

QCN

header 정보 확인하기

<header>
    <application>HDS</application>
    <project>TST</project>
    <transaction>TST010</transaction>
    <datasource>DB01</datasource>
    <use>Y</use>
    <desc>데이터베이스 거래 테스트 예제</desc>
</header>

header 는 삭제 가능하며 이때 디렉토리와 파일명으로 내용이 구성되며 datasource 는 module.json 의 DefaultDataSourceID 항목을 사용

QCN

statement 매개변수 데이터 타입 (1/2)

<param id="@UserID" type="String" length="255" value="NULL" />

대부분의 경우 데이터베이스에 상관없이 다음의 데이터 타입을 사용

  • String

  • Int32, Int64, Int16

  • Long, Decimal, Currency, Double, Float

  • DateTime, Date, Time

QCN

statement 매개변수 데이터 타입 (2/2)

DbType 열거형 참조

QCN

statement 매개변수 데이터베이스 데이터 타입 (1/2) · 세부 1/3

필요한 경우 native="Y" 속성을 선언 하여 다음의 데이터베이스의 고유 데이터 타입을 사용

QCN

statement 매개변수 데이터베이스 데이터 타입 (1/2) · 세부 2/3

QCN

statement 매개변수 데이터베이스 데이터 타입 (1/2) · 세부 3/3

QCN

statement 매개변수 데이터베이스 데이터 타입 (2/2)

QCN

쿼리 계약의 완료 기준

  • 소스 설정과 실행본 설정을 구분합니다.
  • 연결 문자열 보호 방식과 대상 호스트를 확인합니다.
  • header·statement·param을 대조하고 실습 DB에서 결과를 검증합니다.
QCN

발표: 첫 화면의 목표를 말한 뒤 핵심 개념과 예제로 진행합니다. 확인 질문 뒤에는 답할 시간을 주고, 마지막 완료 기준을 남겨 질문을 받습니다. 발표 구성 참고: MIT OpenCourseWare, Patrick Winston, How to Speak (2018), https://ocw.mit.edu/courses/res-tll-005-how-to-speak-january-iap-2018/pages/how-to-speak/

이어지는 코드 조각입니다. 앞뒤 페이지를 순서대로 읽으며 전체 예제의 일부임을 설명합니다.

이어지는 코드 조각입니다. 앞뒤 페이지를 순서대로 읽으며 전체 예제의 일부임을 설명합니다.

질문 후 잠시 기다립니다. 답이 없으면 앞에서 본 예제를 다시 가리킵니다. 확인할 답: DataSourceID, ApplicationID·ProjectID 범위, 실행본 module.json의 연결 정보를 확인합니다. 다음 주제로 넘어가기 전에 차이를 청중의 표현으로 한 번 확인합니다.

질문을 받는 동안 이 확인 기준을 화면에 남깁니다. 청중이 자신의 업무에 적용할 다음 행동 하나를 고르게 합니다.